Skip to content

[SPARK-59291][STREAMING] Add return tags to the public StateSpec methods - #58563

Closed
uros-b wants to merge 2 commits into
apache:masterfrom
uros-b:apidoc-statespec-return
Closed

[SPARK-59291][STREAMING] Add return tags to the public StateSpec methods#58563
uros-b wants to merge 2 commits into
apache:masterfrom
uros-b:apidoc-statespec-return

Conversation

@uros-b

@uros-b uros-b commented Sep 7, 2026 •
edited
Loading

Copy link
Copy Markdown
Member

What changes were proposed in this pull request?

This completes the Scaladoc on the public StateSpec API:

  • Adds @return tags to all nine public methods that lacked them:
    • the four StateSpec.function(...) factory overloads (companion object) -- "a new StateSpec for the mapWithState operation";
    • the five builder methods on the abstract class (initialState x2, numPartitions, partitioner, timeout), which return this.type -- "this StateSpec (to allow chaining)".
  • Adds the missing @tparam KeyType to the second and fourth StateSpec.function(...) overloads, which previously documented only ValueType / StateType / MappedType.

Scaladoc only; no code changes.

Why are the changes needed?

It completes the Scaladoc for the public StateSpec surface so the generated API docs state what each method returns and document every type parameter. The function factories return a freshly built StateSpec, and the builder methods return the same instance to allow fluent chaining (as in the class example, StateSpec.function(mappingFunction).numPartitions(10)); this closes a small, pre-existing doc gap.

Does this PR introduce any user-facing change?

No. Scaladoc-only; no API or behavior change.

How was this patch tested?

N/A -- documentation-only change. The streaming module compiles cleanly.

Was this patch authored or co-authored using generative AI tooling?

Generated-by: Claude Code (Opus 4.8)

uros-b
uros-b commented Sep 7, 2026
View reviewed changes

@uros-b uros-b left a comment

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

PTAL @HyukjinKwon @srowen

@uros-b
uros-b requested review from HyukjinKwon and srowen September 7, 2026 11:18
@uros-b

uros-b commented Sep 11, 2026

Copy link
Copy Markdown
Member Author

soft ping here ^^

@dongjoon-hyun

dongjoon-hyun commented Sep 11, 2026

Copy link
Copy Markdown
Member

Hi, @uros-b . Please be careful in GitHub. Your PR is giving lots of noise to someone who has the valid GitHub Account name like the following. 😄

Screenshot 2026-09-11 at 08 02 42 Screenshot 2026-09-11 at 08 04 10

@dongjoon-hyun

dongjoon-hyun commented Sep 11, 2026

Copy link
Copy Markdown
Member

The doc changes look correct to me: all four function factories build a new StateSpecImpl, and all five builder methods return this.

Could you retitle the PR before merge, e.g. Add return tags to the public StateSpec methods? dev/merge_spark_pr.py strips @ from the PR body but not from the title, so @return would end up in the master commit subject and keep pinging the GitHub user return.

Nit: the 2nd and 4th function overloads are also missing @tparam KeyType. It would be nice to add those here too.

@uros-b uros-b changed the title [SPARK-59291][STREAMING] Add @return tags to the public StateSpec methods [SPARK-59291][STREAMING] Add @return tags to the public StateSpec methods Sep 12, 2026
@uros-b uros-b changed the title [SPARK-59291][STREAMING] Add @return tags to the public StateSpec methods [SPARK-59291][STREAMING] Add return tags to the public StateSpec methods Sep 12, 2026
@uros-b

uros-b commented Sep 12, 2026

Copy link
Copy Markdown
Member Author

My apologies to the innocent GitHub user who I tagged here! That's a super cool username, but I couldn't imagine the inbox...😭

dongjoon-hyun
dongjoon-hyun approved these changes Sep 13, 2026
View reviewed changes

@dongjoon-hyun dongjoon-hyun left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thank you for addressing the comments, @uros-b . The added @tparam KeyType tags look good, and the title no longer contains @.

nit: it would be great to mention the @tparam KeyType additions in the PR description too, since it becomes the commit message.

@uros-b uros-b closed this in 2dcbadb Sep 13, 2026
uros-b added a commit that referenced this pull request Sep 13, 2026
@uros-b
[SPARK-59291][STREAMING] Add return tags to the public StateSpec methods
f29cd30 
### What changes were proposed in this pull request?

This completes the Scaladoc on the public `StateSpec` API:

- Adds `return` tags to all nine public methods that lacked them:
  - the four `StateSpec.function(...)` factory overloads (companion object) -- "a new `StateSpec` for the `mapWithState` operation";
  - the five builder methods on the abstract class (`initialState` x2, `numPartitions`, `partitioner`, `timeout`), which return `this.type` -- "this `StateSpec` (to allow chaining)".
- Adds the missing `tparam KeyType` to the second and fourth `StateSpec.function(...)` overloads, which previously documented only `ValueType` / `StateType` / `MappedType`.

Scaladoc only; no code changes.

### Why are the changes needed?

It completes the Scaladoc for the public `StateSpec` surface so the generated API docs state what each method returns and document every type parameter. The `function` factories return a freshly built `StateSpec`, and the builder methods return the same instance to allow fluent chaining (as in the class example, `StateSpec.function(mappingFunction).numPartitions(10)`); this closes a small, pre-existing doc gap.

### Does this PR introduce _any_ user-facing change?

No. Scaladoc-only; no API or behavior change.

### How was this patch tested?

N/A -- documentation-only change. The `streaming` module compiles cleanly.

### Was this patch authored or co-authored using generative AI tooling?

Generated-by: Claude Code (Opus 4.8)

Closes #58563 from uros-b/apidoc-statespec-return.

Authored-by: Uros <221401595+uros-b@users.noreply.github.com>
Signed-off-by: Uros Bojanic <221401595+uros-b@users.noreply.github.com>
(cherry picked from commit 2dcbadb)
Signed-off-by: Uros Bojanic <221401595+uros-b@users.noreply.github.com>
@uros-b

uros-b commented Sep 13, 2026

Copy link
Copy Markdown
Member Author

Merge Summary:

Posted by merge_spark_pr.py

@uros-b

uros-b commented Sep 13, 2026

Copy link
Copy Markdown
Member Author

Thank you @dongjoon-hyun!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@dongjoon-hyun dongjoon-hyun dongjoon-hyun approved these changes
@srowen srowen Awaiting requested review from srowen
@HyukjinKwon HyukjinKwon Awaiting requested review from HyukjinKwon

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

2 participants

@uros-b @dongjoon-hyun